@material/switch

What is @material/switch?

@material/switch is a Material Design implementation of a switch component. It provides a customizable and accessible switch that can be used to toggle between two states, such as on and off. The package is part of the Material Components for the web, which ensures a consistent look and feel across different platforms.

What are @material/switch's main functionalities?

Basic Switch

This is the most basic usage of the @material/switch component. It renders a switch that can be toggled between on and off states.

<mwc-switch></mwc-switch>

Disabled Switch

This example shows how to render a switch that is disabled and cannot be interacted with.

<mwc-switch disabled></mwc-switch>

Switch with Label

This example demonstrates how to use a switch with a label. The label is provided using the mwc-formfield component.

<mwc-formfield label="Toggle me"><mwc-switch></mwc-switch></mwc-formfield>

Switch with Event Listener

This example shows how to add an event listener to the switch to handle state changes.

document.querySelector('mwc-switch').addEventListener('change', (e) => { console.log('Switch state:', e.target.checked); });

Other packages similar to @material/switch

react-switch

react-switch is a lightweight switch component for React. It provides similar functionality to @material/switch but is designed specifically for React applications. It offers customization options for colors, sizes, and labels.

rc-switch

rc-switch is a React component that provides a switch UI element. It is highly customizable and supports various themes and styles. It is similar to @material/switch but is more focused on providing a flexible API for React developers.

vue-js-toggle-button

vue-js-toggle-button is a Vue.js component for creating toggle buttons. It offers similar functionality to @material/switch but is designed for Vue.js applications. It supports customization of colors, sizes, and labels.

README

Selection controls: switches

Selection controls allow the user to select options.

Switches toggle the state of a single setting on or off. They are the preferred way to adjust settings on mobile.

Contents

• Using switches
• Switches
• Other variants
• API
• Usage within web frameworks

Using switches

Use switches to:

• Toggle a single item on or off, on mobile and tablet
• Immediately activate or deactivate something

Installing switches

npm install @material/switch

Styles

@use '@material/switch/styles';

JavaScript instantiation

The switch requires JavaScript to function, so it is necessary to instantiate MDCSwitch on the mdc-switch element.

import {MDCSwitch} from '@material/switch';

for (const el of document.querySelectorAll('.mdc-switch')) {
  const switchControl = new MDCSwitch(el);
}

Note: See Importing the JS component for more information on how to import JavaScript.

Switches

Switch example

<button id="basic-switch" class="mdc-switch mdc-switch--unselected" type="button" role="switch" aria-checked="false">
  <div class="mdc-switch__track"></div>
  <div class="mdc-switch__handle-track">
    <div class="mdc-switch__handle">
      <div class="mdc-switch__shadow">
        <div class="mdc-elevation-overlay"></div>
      </div>
      <div class="mdc-switch__ripple"></div>
      <div class="mdc-switch__icons">
        <svg class="mdc-switch__icon mdc-switch__icon--on" viewBox="0 0 24 24">
          <path d="M19.69,5.23L8.96,15.96l-4.23-4.23L2.96,13.5l6,6L21.46,7L19.69,5.23z" />
        </svg>
        <svg class="mdc-switch__icon mdc-switch__icon--off" viewBox="0 0 24 24">
          <path d="M20 13H4v-2h16v2z" />
        </svg>
      </div>
    </div>
  </div>
</button>
<label for="basic-switch">off/on</label>

Switch states

Switches can be on or off. Switches have enabled, hover, focused, and pressed states.

Other variants

Initially disabled switch

Add the disabled attribute to the mdc-switch element to disable the switch. This logic is handled by the MDCSwitch.disabled property, but you'll want to avoid a FOUC by initially adding this attribute.

<button id="disabled-switch" class="mdc-switch mdc-switch--unselected" type="button" role="switch" aria-checked="false" disabled>
  <div class="mdc-switch__track"></div>
  <div class="mdc-switch__handle-track">
    <div class="mdc-switch__handle">
      <div class="mdc-switch__shadow">
        <div class="mdc-elevation-overlay"></div>
      </div>
      <div class="mdc-switch__ripple"></div>
      <div class="mdc-switch__icons">
        <svg class="mdc-switch__icon mdc-switch__icon--on" viewBox="0 0 24 24">
          <path d="M19.69,5.23L8.96,15.96l-4.23-4.23L2.96,13.5l6,6L21.46,7L19.69,5.23z" />
        </svg>
        <svg class="mdc-switch__icon mdc-switch__icon--off" viewBox="0 0 24 24">
          <path d="M20 13H4v-2h16v2z" />
        </svg>
      </div>
    </div>
  </div>
</button>
<label for="disabled-switch">off/on</label>

Initially "on" switch

Add the mdc-switch--selected class and aria-checked="true" attribute to the mdc-switch element to toggle the switch to "on". This logic is handled by the MDCSwitch.selected method, but you'll want to avoid a FOUC by initially adding this class and attribute.

<button id="selected-switch" class="mdc-switch mdc-switch--selected" type="button" role="switch" aria-checked="true">
  <div class="mdc-switch__track"></div>
  <div class="mdc-switch__handle-track">
    <div class="mdc-switch__handle">
      <div class="mdc-switch__shadow">
        <div class="mdc-elevation-overlay"></div>
      </div>
      <div class="mdc-switch__ripple"></div>
      <div class="mdc-switch__icons">
        <svg class="mdc-switch__icon mdc-switch__icon--on" viewBox="0 0 24 24">
          <path d="M19.69,5.23L8.96,15.96l-4.23-4.23L2.96,13.5l6,6L21.46,7L19.69,5.23z" />
        </svg>
        <svg class="mdc-switch__icon mdc-switch__icon--off" viewBox="0 0 24 24">
          <path d="M20 13H4v-2h16v2z" />
        </svg>
      </div>
    </div>
  </div>
</button>
<label for="selected-switch">off/on</label>

API

CSS classes

CSS Class	Description
mdc-switch	Mandatory, for the parent element.
mdc-switch--unselected	Optional, styles the switch as unselected ("off")
mdc-switch--selected	Optional, styles the switch as selected ("on")
mdc-switch__track	Mandatory, for the track element.
mdc-switch__handle-track	Mandatory, for the handle's track element.
mdc-switch__handle	Mandatory, for the handle element.
mdc-switch__shadow	Mandatory, for the shadow effect.
mdc-elevation-overlay	Mandatory, for the shadow effect's overlay in dark mode.
mdc-switch__ripple	Mandatory, for the ripple effect.
mdc-switch__icons	Mandatory, for the icons.
mdc-switch__icon	Mandatory, for the icon elements.
mdc-switch__icon--on	Mandatory, for the on icon.
mdc-switch__icon--off	Mandatory, for the off icon.

Theme mixin

The switch may be customized using the theme() mixin and providing an MDC Theme string (such as primary) or other values to the theme keys.

@use '@material/switch';
@use '@material/theme/color-palette';
@use '@material/theme/shadow-dom';

// Include for IE11 support
// @include shadow-dom.enable-css-selector-fallback-declarations(true);

.my-switch {
  @include switch.theme((
    selected-handle-color: color-palette.$teal-600,
    selected-track-color: color-palette.$teal-300,
  ));
}

View the theme file for available keys and built-in themes.

MDCSwitch properties

Property	Value Type	Description
disabled	Boolean	Indicates whether or not the switch is disabled.
selected	Boolean	If true, the switch is on. If false, the switch is off.

Usage within web frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a switch for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

See MDCSwitchAdapter and MDCSwitchFoundation for up-to-date code documentation of switch's foundation API.

Changelog

13.0.0 (2021-09-24)

Bug Fixes

• Fix missing $ripple-target param for ripple mixin (1340ee9)
• banner: Adjusting theme api selectors to use mdc-button. (15981e9)
• banner: Correcting incorrect theme values passed through to button's theme-mixin. (0de2f2e)
• banner: exclude source from npm package (#7381) (d48a017), closes #7360
• banner: Removing action-<state>-label-text-color values from MDC light-theme map. (d97f8f1)
• button: cleanup outlined button theme keys (28d0d75)
• button: fix touch target reset in context of link buttons (3b8d442)
• button: remove negative padding around icons (d470693)
• button: remove rem/em transformers from typography theme-styles (a395972)
• button: stack ripple behind content (e1e69fd)
• density: typo in variable exports (6df682e)
• dom: Support providing an owner document for announcer messages. (6236f35)
• elevation: reduce warnings when not providing elevation tokens (adb9f1a)
• iconbutton: Fix icon button theme keys/light theme values based on updated tokens. (42d175e)
• menu: apply elevation overlay to new lists (0ad12ed)
• sass: Wrap templated calc expressions in strings (818f4ee), closes #7391
• slider: Reorder such that dragstart event is emitted before any other events when handling drag start. (877e3fb)
• slider: Replace innerHTML with firstChild (37d4db8)
• Fix compilation issues with TypeScript 4.4 (7246447)
• switch: add pointer cursor (12f5622)
• switch: distribute correct css (#7292) (7b6bcb8)
• switch: elevation theme custom properties not working (2865629)
• switch: use correct colors for icons in all HCM themes (d86fb6f)
• theme: ensure state selectors negate properly (7249a30)
• tooltip: Add a getActiveElement() method to MDCTooltipAdapter to delegate getting the active element from the correct document. (e334676)
• tooltip: Adjust tooltip focusout handler. Ensures that interactive tooltips remain open when ChromeVox uses linear navigation to read non-focusable content inside the tooltip. (7c96e6b)
• tooltip: non-persistent tooltips disappear on scroll (1f9259b)
• update combined mdc package to use new switch CSS (077dcfc), closes #7304
• tooltip: allow the Mac zoom service to access plain tooltip contents (510cf90)

Code Refactoring

• fab: Deprecate legacy Fab theme mixins (83bdd02)
• iconbutton: Forward only theme mixins from MDC icon button index module. (0a90693)
• theme: Rename validate-keys() to validate-theme() (2fb068f)

Features

• button: add custom props to outlined button theme-styles (bf405d2)
• button: add custom props to protected button theme-styles (4ca11fe)
• button: add custom props to text button theme-styles (3dd6110)
• button: add missing transitions to box-shadow/border (3b92903)
• button: add static-styles-without-ripple for MWC consumption (f4241a4)
• button: add theme mixin that emits custom properties instead (4c40586)
• button: emit custom properties fill button theme-styles (a80c8b2)
• button: m3 elevation + icon base theme modules (2da3606)
• button: resolve elevation keys in theme mixin (843342f)
• chips: Add theming Sass mixin to MDC Filter Chip (8390093)
• chips: Add theming Sass mixin to MDC input & suggestion Chip (860ad06)
• chips: Added theme mixins to Assist Chip (d4e16a6)
• chips: Export all non-deprecated members through chips index (8647986)
• chips: Rename action's exported members to avoid naming collisions (b49359c)
• chips: Rename chip set's exported members to avoid naming collisions (13db34b)
• chips: Rename chip's exported members to avoid naming collisions (470bd34)
• data-table: Implement row click feature to MDC data table (8de07c0)
• data-table: use new select + list templates for pagination (08398f8)
• dialog: Add theme styles mixin to dialog (21ece53)
• dialog: Separate static styles from dialog core-styles mixin (43d2eed)
• fab: create theming file for small fabs (d082790)
• fab: prepare fab-extended for theming in MWC (ce25bc3)
• iconbutton: Add .mdc-icon-button--display-flex class that centers icon via flexbox. When using the new theme API, the icon button should have this class. (8355e14)
• iconbutton: Add MDC theme mixin that declares custom properties. (fa7520f)
• iconbutton: Add theme styles mixin. (65aa63b)
• menu: Added getter method to check fixed position status of menu (fb76c50)
• menu: Adds option to prevent focus from being restored after an item action. (65084ba)
• select: start compatibility work for evolution lists (e8554db)
• theme: Added validate-theme-keys() mixin to validate theme keys only (457d89a)

BREAKING CHANGES

• menu: Adds new menu adapter method:

  /**

  • @return the attribute string if present on an element at the index
  • provided, null otherwise. */ getAttributeFromElementAtIndex(index: number, attr: string): string|null;

PiperOrigin-RevId: 398575780

• iconbutton: MDC iconbutton _index Sass module will only export theme mixins.

PiperOrigin-RevId: 391773229

• theme: Renamed Sass mixins validate-keys() to validate-theme() in @material/theme

PiperOrigin-RevId: 390671152

• fab: Renamed Fab's mixins to deprecate legacy theme mixins.

PiperOrigin-RevId: 387378201